<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>rbxi :: readme :: setup instructions</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css">
@media print {
	#topnav,#bottomnav {
		display:none;
	}
}
body {
	font-size:95%;
	font-family:sans-serif;
}
pre {
	padding:0.5em 1em;
	background:#ddd;
	font-family:'lucida mono', terminal, console, monospace;
}
#maincontainer{
	padding:.5em 1em;
	max-width:54em;
}
h1,h2,h3,h4,h5,h6 {
	margin:0 0 0 0;
	text-align:left;
}
h1 {
	font-size:2.3em;
	border-top:5px double #000;
	padding:.2em 0;
}
h2 {
	font-size:2.0em;
	border-top:3px solid #000;
	margin-top:1em;
	padding:.2em 0;
}
h3 {
	font-size:1.7em;
	border-top:1px solid #000;
	padding:.2em 0;
}
h4 {font-size:1.4em;}
h5 {font-size:1.1em;}
h6 {font-size:1.0em;}

p {
	margin-top:.2em;
}
a:hover {
	text-decoration:none;
}
li {
	margin-bottom:.3em;
}
.small {
	font-size:80%;
}
#topnav {
	margin-bottom:1em;
	font-size:10px;
}
#bottomnav {
	border-top:5px double black;
	padding-top:.7em;
	margin-top:1em;
	font-size:8px;
}
#topnav ul, #bottomnav ul {
	margin:0;
	padding:0;
}
#topnav li,#bottomnav li {
	display:inline;
	margin:0;
	padding:0;
}
</style>
<link rel="shortcut icon" href="http://smxi.org/inc/favicon.ico">
</head>
<body id="top">
<div id="maincontainer">

<h1>Read-me for Setting Up rbxi</h1>
<pre>
Filename: rbxi-readme.htm
Version: 2.7.2
</pre>

<ul>
	<li><a href="#rbxi-introduction">Introduction</a> :: Brief overview of the script and readme.</li>
	<li><a href="#rbxi-package-contents">Bzip Package Contents</a> :: List of the files and directories contained in rbxi.tar.bz2 download file.</li>
	<li><a href="#rbxi-options">Script Options</a> :: parameters and options for rbxi, with explanations of each.</li>
	<li><a href="#rbxi-backup-formatting">Backup Partition Formatting</a> :: Some notes on how to format your backup partitions.</li>
	<li><a href="#rbxi-rsync-remote">Using rsync To or From Remote Machines</a> :: It takes a bit of a practice to get rysnc to backup to or from remote machines.</li>
	<li><a href="#rbxi-excludes">Exclude File Information</a> :: Information on how to setup and configure rsync and rdiff-backup exclude files, and related syntax matters.</li>
	<li>
	<a href="#rbxi-values-setup">How to Setup rbxi-values Variables and Data</a> :: This is the most important part of rbxi, it's what will actually make your backups do what you want them to do. Covers the following:
		<ul>
			<li><a href="#rbxi-values-main-script">Path Variables in Main Script</a> - You should almost never need to change these.</li>
			<li>
				<a href="#rbxi-values-user-variables">User Specific Variables</a> -  Change as Required. This is REQUIRED for rbxi to run on your system. This is where you actually create and set the backup job, that is.
				<ul>
					<li><a href="#rbxi-values-app-paths">Application Paths and Data</a></li>
					<li><a href="#rbxi-values-extra-args">Rsync/Rdiff-backup Extra Arguments</a> - Add optional arguments to send to the backup application.</li>
					<li><a href="#rbxi-values-mount-directory">Primary Destination Directory for Backup</a></li>
					<li><a href="#rbxi-values-primary-backup-directory">Primary Backup Job Directories in Destination Directory</a></li>
					<li><a href="#rbxi-values-backup-destination-subdirectory">Backup Destination Sub Directories</a></li>
					<li><a href="#rbxi-values-directory-output-descriptions">Script Backup Directory Output Descriptions</a></li>
					<li><a href="#rbxi-values-backup-source-paths">Backup Source Paths</a></li>
					<li><a href="#rbxi-values-mount-umount">Mount / Umount Data</a> - Set mount/umount commands.</li>
					<li><a href="#rbxi-values-backup-jobs">Backup Job Preset Section</a></li>
					<li><a href="#rbxi-values-user-functions">User Defined Pre/Post Mount/Umount Functions</a></li>
					<li><a href="#rbxi-values-user-actions">User Defined Start/Finish/Error Actions (emails)</a></li>
					<li><a href="#rbxi-values-clean-delete">Clean Delete Backup Skip Section</a></li>
					<li><a href="#rbxi-values-misc-options">Miscellaneous Script Options Section</a></li>
					<li><a href="#rbxi-values-final-step">Final Configuration Step</a> - rbxi will not run at all if you do not complete this final step.</li>
				</ul>
			</li>
		</ul>
	</li>
	<li><a href="#rbxi-static-variables">Static Variables</a> :: These are core rbxi variables, and shouldn't require any changes in general.</li>
	<li><a href="#rbxi-functions">Rbxi Functions</a> :: You would not change these in general unless you like hacking on scripts.</li>
</ul>

<h2 id="rbxi-introduction">Introduction to rbxi</h2>

<p>
The rbxi script is designed to only require a single setup, one time.
Any updates to the script should only be new features, which if your system is the
way you want, you should not need. But feel free to check the script homepage
now and then to see if a new feature might be implemented that would be useful
to you.
</p>
<p>
Please do not change anything in the FUNCTIONS section unless you
are reasonably comfortable with shell scripting. If you do change something and you
break the script, I will not give any support to you, unless it's an interesting problem.
</p>
<ul>
	<li>Script Bzip File Download URL: <a href="http://smxi.org/rb">http://smxi.org/rb</a></li>
	<li>Install Directions: <a href="http://smxi.org/install.htm#rbxi">http://smxi.org/install.htm#rbxi</a></li>
	<li>Script Home page: <a href="http://techpatterns.com/forums/about831.html">http://techpatterns.com/forums/about831.html</a></li>
</ul>

<h3>Required Programs to Run rbxi</h3>

<p>
The only currently required program, aside from <strong>rsync</strong> or <strong>rdiff-backup</strong>,  you need
for rbxi to run is: <strong>lsof</strong>
</p>
<p>
All other tools should be standard for bash.
</p>
<p>
To see if you have <strong>lsof</strong>, simply run this command:
</p>
<pre>
which lsof
</pre>
<p>
If it show the path, you have it.
</p>

<h3>rbxi Script Setup</h3>

<p>
You must customize the USER VARIABLE section and the rbxi excludes to fit your system and requirements
before running this script. For most users, that should be all that is required.
</p>
<p>
See the <a href="#rbxi-values-setup">rbxi-values setup section</a> and <a href="#rbxi-excludes">rbxi excludes</a> on how to do that.
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h2 id="rbxi-package-contents">rbxi.tar.bz2 Package Contents</h2>

<p>
This bzipped package should contain the following files and directories:
</p>
<ol>
	<li>
<pre>
rbxi
</pre>
		<p>
		This is the main program file. Make sure to use
		</p>
<pre>
chmod +x rbxi
</pre>
		<p>
		to make it executable, although it should already be executable.
		</p>
	</li>
	<li>
<pre>
rbxi-data/ # main rbxi data directory
</pre>
	</li>
	<li>
<pre>
rbxi-data/excludes-root.txt (for rdiff-backup)
rbxi-data/excludes-root-rsync.txt (for rsync)
</pre>
		<p>
		These have the standard root excludes. Do not delete any of these except for:
		</p>
<pre>
/var/cache/apt/archives/*
</pre>
		<p>
		And only delete that if you want to backup your deb archives.
		</p>
	</li>

	<li>
<pre>
# for rdiff-backup
rbxi-data/excludes-home.txt
rbxi-data/excludes-data-&lt;1-10>.txt
# and for rsync
rbxi-data/excludes-home-rsync.txt
rbxi-data/excludes-data-&lt;1-10>-rsync.txt
</pre>
		<p>
		These are blank files. Use them to add more excludes if required to your backup.
		</p>
	</li>

	<li>
<pre>
rbxi-data/rbxi-values
</pre>
		<p>
		This file contains all your user variables, use this to create your values
		for your backup. This replaces the old 1.x method of having these values on
		the actual rbxi file, so you can now easily upgrade rbxi without having to
		update or change anything.
		</p>
		<p>
		Note: you can create any number of these rbxi-values files, and load
		alternate values files by using the -V option. See rbxi -h for details.
		File must be in rbxi-data, and the name must be rbxi-values-&lt;anything>
		The value for -V must be &lt;anything>, and the file will be tested for.
		</p>
	</li>

	<li>
<pre>
rbxi-data/readme-rbxi.htm
</pre>
		<p>
		This HTML read-me file should help you set up rbxi. Please make sure to read it before
		giving up on the setup, rbxi requires some end user learning to really work as expected.
		</p>
	</li>
</ol>
<p>

<p class="small">
<a href="#top">top</a>
</p>

<h2 id="rbxi-options">Script Options and Parameters</h2>

<p>
The script can be started with a variety of different options, and the same options can be used to create <a href="#rbxi-values-backup-jobs">backup Jobs (-J)</a>.
</p>

<h3>Add/Skip Override Components and -J (Job) Preset Values</h3>

<pre>
-A Add backup component. Overrides user set B_SKIP_DATA.. (d|h|hr|1-10)
   d - add all DATA; h - add HOME; r - add ROOT; add DATA 1-10
   Normal use is with -J option set to override -S rbxi-values settings
   for SKIP variables.
-B Change default backup directory (1-10).
-C (rsync only) Clone root/home. Skips all data backups. Moves files
	directly to mounted location. Sets the main mount subdirectory too,
	then transfers files directly into that directory.
   Takes parameters: (h|r|1-10). Clone root, home, or a data direcory.
-D Change default backup sub directory (1-10)
-E [1-5]:[1-5]:[1-5] - note, you can skip any number, like: -E 2:: which will
   then only run start actions. Requires user set up of actions to run rbxi
   start, finish, and rbxi error. 
-M Use alternate mount/umount set (1-10) - these are set in rbxi-values.
   They can be null, so make sure you have the right number for your selection.
-o [rb|rs] Override default backup application: use rsync/rdiff-backu
-P [1-5]:[1-5]:[1-5] - note, you can skip any number, like: -P 2:: which will
   then only run pre mount tasks. Requires user set up of functions to run
   pre mount, post mount, and post umount. 
-S Skip backup component (d|h|hr|1-10)
   d - skip all DATA; h - skip HOME; r - skip ROOT; skip DATA 1-10
</pre>
<p>
In general, avoid using A, D, M, S unless you are creating a backup job -J, or if you want
temporarily skip (-S) or add (-A) a specific directory.
</p>
<p>
-S and -A can be used repeatedly, like so: -S 2 -S 5 -S 9
</p>
<p>
Remember, -A should only be used to override SKIP... that has been set in rbxi-values.
</p>
<p>
-C overrides -A which overrides -S. -C will only clone the specific directory you set,
directly to the destination directory, and switches off all other backup directories.
</p>
<p>
-C overrides -D, or default backup subdirectory, and sets it to null.
</p>
<p>
-D overrides default main mount backup directory, and uses that for -M
</p>

<h3>Auto Run Options</h3>

<pre>
-b Runs the backup without any interactive questions. Automatically, that is.
   -b will simply create a backup based on the current month, assign it to the
   correct primary backup directory, then execute the backup.
-c Automatic backup, clean older files, for non-interactive. Cleans and runs
   normal backup.
-d First deletes the old backups, then runs the backup non-interactively
   as with -b.
   Caution: all your previous backups from that backup directory will be
   eliminated if you use this. Permanently.
</pre>
<p>
-b, -c, and -d are also well suited for running the backup with a cron job, automatically, that is.
</p>

<h3>Job Option</h3>

<pre>
-J Start preset backup job (1-10)
</pre>
<p>
Create preset jobs, 1-10, in rbxi-values, using script arguments. Use presets like -A, -B, -o,
-D to create a custom job for future use.
</p>

<h3>Miscellaneous Options</h3>

<pre>
-h The help menu, these options.

-L Create symbolic link in /usr/local/bin to rbxi. You must be root to use this.
   It will check for the link and create it if it's missing.

-r Runs --dry-run option, which emulates the backup job without actually running
   any of it, including the -d delete option.
   
-R Show script readme file. Requires one of the following console browsers: 
	links2 elinks w3m links lynx

-s Runs the backup using spinning wheel progress indicators.
   Warning: in order to do this, the script puts the actual backup jobs
   in the background, so you can't kill them the normal way, with ctrl+c
   if you want to stop the backup. Keep that in mind.

   -s is useful, besides being eye candy, for letting you know that the
   script is actually doing something while it sits there working on your
   deletions or backups.

-U Update script manually from svn server. It will update it to where-ever
   you have it installed.

-v Show script version and last used information. Also shows last time you
   did a backup and which backup directory was used. This should help people
   like me who can't remember.

-V Use alternate rbxi-values file. Syntax: rbxi-values-&lt;whatever you want>
   File must be located in rbxi-data, and must have the syntax of:
   rbxi-values-&lt;something>
</pre>

<h3>Mount/Umount</h3>

<p>
If the device is automounted, the script will check to make sure it's path is present, and
if the script uses mount/unmount option, that contains a test as well for failed mounts.
</p>
<pre>
   -m Skip the mounting option. If present, the script will not use your
   preset mount/umount values, and will not try to mount anything. Only use
   if you have a good reason to do so.
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h2 id="rbxi-backup-formatting">Backup Partition Formatting</h2>

<p>
USING FAT OR FAT32 FORMATTED DRIVES MAY DESTROY YOUR SYSTEMS INTEGRITY ON RESTORE OPERATIONS!
</p>
<p>
This is because fat file systems do not allow any advanced permissions, which all unix systems
rely on to maintain security and user privileges. Also fat32 has a max file size of about
4 gigabytes.
</p>
<p>
In order to preserve your file ownership and permissions, you must backup to a reasonably
robust file system. I recommend either ext2 or ext3 if it's an external drive, and whatever
you like internally as long as it's not a FAT type system, which has no support for advanced
file ownership or permissions.
</p>
<p>
Recent developments with reiserfs (like Hans Reiser's recent conviction for murder, as well as SUSE dropping all but maintenance support for Reiserfs) suggest that reiser file systems are not a good option for long term data storage, unfortunately.
</p>
<p>

<p class="small">
<a href="#top">top</a>
</p>

<h2>Script Usage</h2>

<p>
Script must be run as root, the contents of rbxi.tar.bz2 should all have been unzipped
into the same directory. It doesn't matter where you put those files though, as long
as you keep them together.
</p>
<p>
Make sure to have your backup drive or partition mounted before you start script unless
you are using the auto mount/unmount options in the script. If the drive or partition is not
present, script exits with an error telling you this.
</p>
<p>
For normal useage, when you run the script, it will check root/backup partition, then ask
you if you want to run the standard backup, which either creates a new, or adds to an existing,
backup directory.
</p>
<p>
If you select the delete and backup option, the script will ask you if you are sure
you want to do that.
</p>
<p>
Once you set the primary variable values as indicated below, you shouldn't need
to change this script much, except mayby adding some exclude items to the exclude files,
or possibly adding or removing a backup option.
</p>

<h3>Rdiff-backup and Rsync Man Files</h3>

<p>
SEE THE man FILES FOR MORE INFORMATION ON HOW TO USE rdiff-backup/rsync FEATURES:
man rdiff-backup OR man rsync
</p>
<p>
Unlike most man files, the rdiff-backup and rysnc man files are filled with clear explanations and examples, and can
show you how to do pretty much anything you can imagine.
</p>

<h3>Things to be Careful About When Running a Backup</h3>

<p>
Close anything that might change files while you backup, like your email program,
irc chat, or anything else that might change while you are doing your backup.
</p>
<p>
Remember to add the path to the backup partition to the exclude lists if your
backup drive or directory is mounted somewhere else than in /media.
</p>
<p>
You don't want to create backups of your backups after all!
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h2 id="rbxi-rsync-remote">Using rsync TO or FROM Remote Machines</h2>

<h3>Backing Up TO Remote Machines</h3>

<p>
For default job, simply set, if the remote machine is the backup destination,
ie, you are backing up your local machine TO the remote machine:
</p>
<pre>
BACKUP_MOUNT_POINT_RS='username@remotemachine:/path/on/remote/machine/to/backup/directory'
</pre>
<p>
NOTE: you do NOT need to use:
</p>
<pre>
BACKUP_MOUNT_POINT_DIRECTORY_RS= can be blank in this case, unless you want to have it point somewhere.
</pre>
<p>
Then set the backup DIR name:
</p>
<pre>
DATA_1_DIR='machine-1'
</pre>
<p>
And that's it.
</p>

<h3>Backing Up FROM Remote Machines</h3>

<p>
For backing up REMOTE directories TO your local machine, you do it the other way:
</p>
<pre>
DATA_1_PATH='user@remotemachine:/path/to/directory/TO-backup/'
</pre>
<p>
Note that you must also set:
</p>
<pre>
DATA_1_DIR='backup-name'
</pre>
<p>
unless you use the -C clone option, in that case:
</p>
<pre>
BACKUP_MOUNT_POINT_RS='/media/backup'
BACKUP_MOUNT_POINT_DIRECTORY_RS='/backup-rs' #if you needed a subdirectory
</pre>
<p>
and then
</p>
<pre>
DATA_1_PATH='user@remotemachine:/path/to/directory/TO-backup/'
DATA_1_DIR=''
</pre>
<p>
Then you'd set the other directories to NOT backup  using either -S skip flags
or hard coding it with SKIP flags in the values file.
</p>
<pre>
B_SKIP_DATA_X...
</pre>
<p>
And that's it.
</p>

<h3>Learning the Ins and Outs of Remote Backup</h3>

<p>
This isn't super easy to understand, and it takes some trial and error to get it right.
</p>
<p>
Whatever you do, MAKE SURE TO USE THE <strong>--dry-run</strong> OPTION UNTIL YOU ARE SURE THE BACKUP IS WORKING
AS EXPECTED, OTHERWISE THE RESULTS COULD BE DANGEROUS!
</p>

<p class="small">
<a href="#top">top</a>
</p>

<p>

<h2 id="rbxi-excludes">Exclude File Information</h2>

<p>
The idea of exclude files is very simple, but there are some things to watch
out for.
</p>

<h3>Main Points on Using Excludes</h3>

<p>
The main syntax you need to understand for creating an exclude list is this:
</p>
<ol>
	<li>
	<strong>/some/directory</strong> - Excludes any file or directory called: directory in <strong>/some</strong>
	and also excludes any directory or file contained in that.
	</li>

	<li>
	<strong>/some/directory/*</strong> - Backs up the directory <strong>/some/directory</strong>, but not its contents.
	</li>

	<li>
	This sequence [ note the <strong>+</strong> with a space after it preceding <strong>/some/directory/main</strong> ]:
<pre>
+ /some/directory/main
/some/directory
</pre>
	</li>
</ol>

<p>
will backup the directory <strong>/some/directory/main</strong> and its contents, but will not back
up anything else in <strong>/some/directory</strong>.
</p>
<p>
It is important to understand that rdiff-backup/rsync first accepts the + items, which means
include this in the backup, then after that you add the normal exclude case. The order
is important, if you put the include case after, it won't get included, if it's before
it will get included.
</p>
<p>
So when you have a list and you want to include one directory in a parent directory that
is excluded, the include item, with + /some/path must come first.
</p>
<p>
For more information, read: man rdiff-backup or man rsync
</p>

<h3>Backup From Outside the Running Operating System</h3>

<p>
First, if you running the backup from outside the operating system that is
being backed up, the exclude file paths must reflect that.
</p>
<p>
So you need to change for example a <strong>/sys/*</strong> in <strong>/dev/hda2</strong> in <strong>roots-excludes.txt</strong>
that is currently mounted in <strong>/media/hda2</strong> to: <strong>/media/hda2/sys/*</strong>
</p>
<p>
However, this script is designed to allow smooth, complete backups from inside
your operating system, so you should rarely need this change. It's much easier
after all running the backup from in the OS than having to reboot into another one.
</p>

<h3>Exclude File Syntax</h3>

<p>
NOTE: for rsync, you need to use <strong>**</strong> for recursive rules, not <strong>*</strong>. rdiff-backup is picky
about this, rsync works as you'd expect: <strong>**</strong> is anything including <strong>/</strong>, <strong>*</strong> is a directory/file.
</p>
<p>
rdiff-backup basically only supports this:
</p>
<pre>
**/usr/* will include/exclude all directories with /usr/ in their path, period
/usr/** will include/exclude everythiung in /usr
/usr/* will include/exclude files/directories one level below usr
/usr/ will include/exclude /usr if the directory has content, and not if it's empty
/usr will include/exclude /usr
</pre>

<h3>Rsync Specific Exclude Path Information</h3>

<p>
For any non root backups, you need to understand that rsync starts the exclude/include path
not absolutely, but relative to the path of the thing being backed up, so for example you
would NOT use:
</p>
<pre>
/home/fred/.qt
</pre>
<p>
to exclude fred/.qt in the /home backup, but would rather use:
</p>
<pre>
/fred/.qt
</pre>
<p>
or better
</p>
<pre>
/*/.qt
</pre>
<p>
which would exclude all users in /home
</p>
<p>
<strong>*</strong>/ only stays within the directory it's in, but <strong>**</strong> includes <strong>/</strong> as a super wildcard, so,
again, say, for <strong>/home</strong>:
</p>
<pre>
**/.qt
</pre>
<p>
would exclude <strong>/home/fred/.qt</strong> AND <strong>/home/fred/blogs/.qt</strong>, but
</p>
<pre>
/*/.qt
</pre>
<p>
would exclude only <strong>/home/usernames/.qt</strong>
</p>

<h4>Things to be Aware Of</h4>

<p>
All rules not starting with <strong>**</strong> must start with <strong>/</strong>, otherwise you get an error.
</p>
<p>
Rules can contain either <strong>** </strong>or <strong>*</strong>, but with <strong>**</strong>  especially, make sure to test it well before you stay with it.
</p>
<p>
I like to start excludes with:
</p>
<pre>
- /*/.qt
</pre>
<p>
and include rules with
</p>
<pre>
+ /*/.qt
</pre>
<p>
Just to make it clear, but in the excludes files, the <strong>-</strong> is optional.
</p>
<p>
When you use either <strong>-</strong> or <strong>+</strong>, they must be followed by a space then the rule.
</p>

<h3>Rdiff-backup Specific Exclude Path Information</h3>

<p>
Paths work as expected, for example
</p>
<pre>
- /home/username/.qt
</pre>
<p>
will exclude that directory in /home
</p>
<p>
Everything else above applies however except for the path oddities.
</p>
<p>

<p class="small">
<a href="#top">top</a>
</p>

<h2 id="rbxi-values-setup">How to Setup rbxi-values Variables and Data</h2>

<p>
You will need to set the paths in rbxi USER SPECIFIC VARIABLES section, using
the file <strong>rbxi-data/rbxi-values</strong>. That overrides anything in the main script, and
if you update rbxi, you will not need to change anything at all.
</p>
<p>
I will run down the variables one by one to explain how to set them correctly.
</p>

<h3 id="rbxi-values-main-script">Path Variables in Main Script</h3>

<p>
Only set these in the main script if things will not work any other way.
</p>
<p>
You have to reset these every time the script updates.
</p>

<pre>
# set this as absolute path for cron jobs if you need to, you'll have to
# update this manually every time you update the script:
LSOF='lsof'

# http://forums.macosxhints.com/archive/index.php/t-73839.html
# note, no other method works reliably to get the true script path, not dirname $0.
if type $LSOF &amp;>/dev/null;then
	SCRIPT_PATH=$( dirname $( $LSOF -p $$ | grep 'REG' | grep -oE "/.*$(basename $0)$" ) )
# checking if the dirname method works
elif [ -d $( dirname $0 )/rbxi-data ];then
	SCRIPT_PATH=$( dirname $0 )
fi

# in worst cases, you can manually set the script directory path here, uncomment
# and make the path explicit. Must not end with /, and must be the full path of
# the rbxi directory rbxi came with.
# You'll have to update this manually every time you update the script:
# example:  SCRIPT_PATH='/home/fred/scripts/rbxi'
# SCRIPT_PATH=''
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h3 id="rbxi-values-user-variables">User Specific Variables - Change as Required</h3>

<p>
These should be the only variables you need to change. I will go down the list
and explain what each group is and how to change it for your system and needs.
</p>
<p>
Please note: some of these have default values already, make sure that the defaults
match your backup needs if you leave them unchanged.
</p>
<p>

<h4 id="rbxi-values-app-paths">Application Paths and Data</h4>

<pre>
########################################################################
#### RSYNC/RDIFF-BACKUP DATA, REQUIRED APPLICATION PATHS ###############
########################################################################

BACKUP_APP='rsync'
</pre>

<p>
Set to either rdiff-backup or rsync. Can be overridden with r/R option. Default is rsync.
</p>
<p>
Change these to the true system paths if you are going to run this as a cron job
like so:
</p>
<pre>
RDIFF_PATH='/usr/bin/rdiff-backup'
</pre>
<p>
or this:
</p>
<pre>
RSYNC_PATH='/usr/bin/rsync'
</pre>
<p>
Use'which rdiff-backup' OR 'which rsync' (no quotes) to find the true path.
</p>
<pre>
RDIFF_PATH='rdiff-backup'
RSYNC_PATH='rsync'
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-extra-args">Rsync/Rdiff-backup Extra Arguments</h4>

<pre>
# For remote, via ssh, include the ssh option
# ie: RSYNC_EXTRA_OPTIONS=' --rsh=ssh '

# ie: RDIFF_EXTRA_OPTIONS=' --terminal-verbosity 5 '
# Only set if you want custom options for either rdiff-backup or rsync,
# otherwise make null: RSYNC_EXTRA_OPTIONS=''
# Defaults are below, to let you see what's going on at least the first time.
# Once rsync works, remove the --dry-run and the backup will actually occur.
RSYNC_EXTRA_OPTIONS=' --dry-run -v '
RDIFF_EXTRA_OPTIONS=' --terminal-verbosity 5 '

# see man rdiff-backup for proper syntax for time. This is set to remove older
# than 60 days incremental backupsThe time  interval  is  an integer followed
# by the character s, m, h, D, W, M, or Y, indicating seconds, minutes,
# hours, days, weeks, months, or years respectively, or a number of these
# concatenated.
# For example, 32m  means  32  minutes, and  3W2D10h7s means
# 3 weeks, 2 days, 10 hours, and 7 seconds.
RDIFF_REMOVE_TIME='60D'
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-mount-directory">Primary Destination Directory for Backup</h4>

<pre>
########################################################################
#### BACKUP (DESTINATION) DIRECTORY PATHS AND INFORMATION ##############
########################################################################
</pre>

<p>
This is your backup mount location, the mount name that you have created for your backup drive or network mount.
</p>
<p>
Remote machines must be in this form: <strong>username@machine:/path/to/backup/destination</strong>
</p>
<pre>
BACKUP_MOUNT_POINT='/media/usbdisk'
BACKUP_MOUNT_POINT_1=''
BACKUP_MOUNT_POINT_2=''
BACKUP_MOUNT_POINT_3=''
BACKUP_MOUNT_POINT_4=''
BACKUP_MOUNT_POINT_5=''
BACKUP_MOUNT_POINT_6=''
BACKUP_MOUNT_POINT_7=''
BACKUP_MOUNT_POINT_8=''
BACKUP_MOUNT_POINT_9=''
BACKUP_MOUNT_POINT_10=''
</pre>
<p>
If you are using rsync, and want a different backup directory, set this to different,
otherwise make it the same as above.
</p>
<pre>
BACKUP_MOUNT_POINT_RS='/media/usbdisk'
BACKUP_MOUNT_POINT_1_RS=''
BACKUP_MOUNT_POINT_2_RS=''
BACKUP_MOUNT_POINT_3_RS=''
BACKUP_MOUNT_POINT_4_RS=''
BACKUP_MOUNT_POINT_5_RS=''
BACKUP_MOUNT_POINT_6_RS=''
BACKUP_MOUNT_POINT_7_RS=''
BACKUP_MOUNT_POINT_8_RS=''
BACKUP_MOUNT_POINT_9_RS=''
BACKUP_MOUNT_POINT_10_RS=''
</pre>
<p>
This is the mounted location of your backup disk or partition. The default assumes
that it is a external drive with the label of 'usbdisk'. Change to your requirements.
Please make sure this does not end with a /, but just the actual partition mount directory
name.
</p>
<p>
NOTE: it is extremely bad practice to backup to the same partition that is being backed up
so if you want to do that don't look here for help or advice.
</p>
<p>
Do not use the /dev/sda1 type names, use the mounted name, like /media/sda1
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-primary-backup-directory">Primary Backup Job Directories in Destination Directory</h4>

<p>
Primary backup job directories, these will be located inside of the BACKUP_MOUNT_POINT
I strongly recommend you use these, because that can help avoid accidently writing the
backup to a directory that did not get mounted, for example: /media/backup prior to
mounting the actual drive  to /media/backup. This is an easy mistake to make.
</p>
<p>
These directories will be found INSIDE your primary mount directory, in the Network or Local drive mount directory, that is. In other words, these directories will be in the mounted backup partition or network drive.
</p>
<p>
DO NOT END the destination directory names below with a '/'
START them with a /
</p>
<pre>
BACKUP_MOUNT_POINT_DIRECTORY='/backup'
BACKUP_MOUNT_POINT_DIRECTORY_1=''
BACKUP_MOUNT_POINT_DIRECTORY_2=''
BACKUP_MOUNT_POINT_DIRECTORY_3=''
BACKUP_MOUNT_POINT_DIRECTORY_4=''
BACKUP_MOUNT_POINT_DIRECTORY_5=''
BACKUP_MOUNT_POINT_DIRECTORY_6=''
BACKUP_MOUNT_POINT_DIRECTORY_7=''
BACKUP_MOUNT_POINT_DIRECTORY_8=''
BACKUP_MOUNT_POINT_DIRECTORY_9=''
BACKUP_MOUNT_POINT_DIRECTORY_10=''
</pre>
<p>
If you are using rsync, set this path to the actual sub directory used in the main backup
directory.
</p>
<pre>
BACKUP_MOUNT_POINT_DIRECTORY_RS='/backup-rs'
BACKUP_MOUNT_POINT_DIRECTORY_1_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_2_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_3_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_4_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_5_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_6_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_7_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_8_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_9_RS=''
BACKUP_MOUNT_POINT_DIRECTORY_10_RS=''
</pre>
<p>
This is the actual directory name of where the backup will go, inside the primary,
generally mounted, or remote ssh/rsh drive.
</p>
<p>
rbxi will test all local directories to see if they exist, and if they don't, will
exit with errors.
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-backup-destination-subdirectory">Backup Destination Sub Directories</h4>

<pre>
####--------------------------------------------------------------------
#### BACKUP JOB DESTINATION SUB DIRECTORIES ----------------------------
####--------------------------------------------------------------------
</pre>

<p>
These directory names are the names your backup job will create for each part you want to run, like home, root, data directories. rsync/rdiff-backup will create these as needed.
</p>

<p>
Do not begin any of the following 4 directory names with a /, just put the name itself
you want rdiff-backup/rsync to create for that particular backup. You do not need to manually
create these sub-directories, rsync or rdiff-backup do it automatically.
</p>
<p>
Important: if any one of these is left blank, no backup of that component will be created.
</p>
<pre>
HOME_DIR='home'
</pre>
<p>
This is the name of the directory that your /home partition will get backed up to inside of
the above primary backup directories.
</p>
<pre>
ROOT_DIR='root-hda1'
</pre>
<p>
This is the name of the directory that your / [root] partition will get backed up to inside
of the above primary backup directories.
</p>
<p>
These are optional backup subdirectories, if these are used the script will backup these
as well as / and /home autumatically.
</p>
<p>
Blank '' means the script does not try to back that item up. This is the backup sub directory name, not the actual data file path
</p>
<p>
Remote machines must be in this form: username@machine:/path/to/backup/source
</p>
<pre>
DATA_1_DIR=''
DATA_2_DIR=''
DATA_3_DIR=''
DATA_4_DIR=''
DATA_5_DIR=''
DATA_6_DIR=''
DATA_7_DIR=''
DATA_8_DIR=''
DATA_9_DIR=''
DATA_10_DIR=''
</pre>
<p>
If used, these are data directory names. Default is blank.
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-directory-output-descriptions">Script Backup Directory Output Descriptions</h4>

<pre>
########################################################################
#### SCRIPT BACKUP OUTPUT DESCRIPTIONS #################################
########################################################################
</pre>

<p>
These variables are simply what the script will print out to you when it runs.
They do not affect what actually is backed up.
</p>

<pre>
DATA_1_DESC='' # for example: DATA_1_DESC='web'
DATA_2_DESC='' # for example: DATA_2_DESC='email'
DATA_3_DESC=''
DATA_4_DESC=''
DATA_5_DESC=''
DATA_6_DESC=''
DATA_7_DESC=''
DATA_8_DESC=''
DATA_9_DESC=''
DATA_10_DESC=''
</pre>
<p>
This is a one or more word description of what is being backed up.
Like this: DATA_1_DESC='my emails'. This is what rbxi will print out
to you as it backs up that directory.
</p>
<p>
This is for DATA_x_DIR and DATA_x_PATH
</p>
<pre>
ROOT_DESC='/dev/hda1'
</pre>
<p>
This just tells you which actual physical partition root is. Change to
your own setup. This is not a path, it's just information for you.
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-backup-source-paths">Backup Source Paths</h4>

<pre>
########################################################################
#### SYSTEM BACKUP SOURCE PATH INFORMATION #############################
########################################################################
</pre>

<p>
These are the actual paths to be used for the backups. Whatever path  you
enter here is what will get backed up.
</p>
<p>
Note: if you leave off the ending /, rsync will create a directory of the last name in
the path, which you probably don't want, so make sure to end these paths with /.
</p>
<p>
All xx_PATH directories are the SOURCE directory, not not the destination.
</p>

<pre>
HOME_PATH='/home/'
</pre>
<p>
Only change this if you are running the backup from outside of the Operating
system that is being backed up. For example, if /home is on /dev/sda3, then
you'd change this to /media/sda3 if you were backing up from example a live cd.
</p>
<p>
SPECIAL NOTE: If you are using any /home excludes, and if you are running the
backup from outside of the operating system/ home partition you are backing up,
you must change the paths in home-excludes.txt to reflect this actual path, for
example:
</p>
<pre>
/home/username/somedata/*
</pre>
<p>
would become
</p>
<pre>
/media/hda3/username/somedata/*
</pre>
<p>
[assuming that your home directory is mounted in a separate partition that is. This path must be the unmounted true path to the /home you are backing up when it's run from outside the OS.
</p>
<p>
Normal useage: do not change
</p>

<h5>Root Path</h5>

<pre>
ROOT_PATH='/'
</pre>
<p>
If backing up from within OS, do not change. If from outside, same as above.
</p>
<p>
SPECIAL NOTE: If you run the script from outside the operating system to be
backed up, you will need to change the root-excludes.txt paths to reflect that.
for exampple, say / in this case is on /dev/hda2, and the partition is mounted
in /media/hda2:
</p>
<pre>
/sys/*
</pre>
<p>
would be
</p>
<pre>
/media/hda2/sys/*
</pre>
<p>
and so on
</p>

<h5>Data Paths</h5>

<pre>
DATA_1_PATH=''
DATA_2_PATH=''
DATA_3_PATH=''
DATA_4_PATH=''
DATA_5_PATH=''
DATA_6_PATH=''
DATA_7_PATH=''
DATA_8_PATH=''
DATA_9_PATH=''
DATA_10_PATH=''
</pre>
<p>
If you are creating more than the default / and /home backups, use this. This
must correspond to the DATA_XX_DIR item above. Set to path of item you want backed
up separately.
</p>
<p>
Note: normally, you will exclude this in either /home or / depending on where the
data is mounted. Just add this path to the relevant home-excludes.txt or root-excludes.txt
To backup the directory name but not it's contents, do this:
</p>
<pre>
/data/*
</pre>
<p>
in the exclude file.
</p>
<p>
If DATA_XX_DIR is blank, this will not get backed up unless you are using the -C,
Clone, option. In all cases however, if you want the backup to occur, the PATHs
here must be real and exist on your system if it is a local path.
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-mount-umount">Mount / Umount Data</h4>

<pre>
########################################################################
#### PARTITION MOUNT/UMOUNT ############################################
########################################################################
</pre>
<p>
Note that MOUNT/UNMOUNT 1-10 are triggered by the -M option, and that
$BACKUP_MOUNT_POINT will be set dynamically from rdiff/rsync BACKUP_MOUNT_POINT set in rbxi
based on the values you used in the config file.
</p>
<p>
If you want the script to automatically mount/umount your backup drive / partition,
use this. If you don't want this, just leave the variables with a blank value.
</p>
<p>
For cron jobs, put the full system path to mount/umount in the command.
</p>
<pre>
MOUNT_BU_DISK='/usr/bin/mount -L backup-disk-1 $BACKUP_MOUNT_POINT'
UNMOUNT_BU_DISK='/usr/bin/umount $BACKUP_MOUNT_POINT'
</pre>
<p>
Use'which mount' OR 'which umount' (no quotes) to find the true path.
</p>
<p>
EXCEPTION: if you want to use a custom DIRECTORY from above, do it like this:
</p>
<pre>
MOUNT_BU_DISK="mount -L backup-disk-1 $BACKUP_MOUNT_POINT_3"
UNMOUNT_BU_DISK="umount $BACKUP_MOUNT_POINT_3"
</pre>
<p>
This will then use the directory you list. This requires double quotes, "", not single, ''.
Of course you can also just hard code in the entire thing if you want, but it's easier to
avoid errors if you just type it in time I find.
</p>
<p>
If you are just needing to change the BACKUP_MOUNT_POINT, just use -B &lt;bu directory number>
instead and rbxi will change that automatically for you, but if you need to put actually
different mount/umount information, then use an alternate MOUNT/UNMOUNT number
</p>
<pre>
MOUNT_BU_DISK='mount -L backup-disk-1 $BACKUP_MOUNT_POINT'
UNMOUNT_BU_DISK='umount $BACKUP_MOUNT_POINT'
MOUNT_BU_DISK_1=''
UNMOUNT_BU_DISK_1=''
MOUNT_BU_DISK_2=''
UNMOUNT_BU_DISK_2=''
MOUNT_BU_DISK_3=''
UNMOUNT_BU_DISK_3=''
MOUNT_BU_DISK_4=''
UNMOUNT_BU_DISK_4=''
MOUNT_BU_DISK_5=''
UNMOUNT_BU_DISK_5=''
MOUNT_BU_DISK_6=''
UNMOUNT_BU_DISK_6=''
MOUNT_BU_DISK_7=''
UNMOUNT_BU_DISK_7=''
MOUNT_BU_DISK_8=''
UNMOUNT_BU_DISK_8=''
MOUNT_BU_DISK_9=''
UNMOUNT_BU_DISK_9=''
MOUNT_BU_DISK_10=''
UNMOUNT_BU_DISK_10=''
</pre>

<p>
Otherwise, set the full command for mount/umount like these samples. I recommend using
either UUID or LABEL mounting to make sure the disk is correctly mounted, since /dev/sdd can
change depending on what you have plugged into your system at that moment.
</p>

<h5>Mount Command Examples</h5>
<p>
For these examples, the disk has the following:
</p>
<pre>
label:		backup-disk-1
uuid:			b833d2c1-b824-4d93-a8c9-74e84226rc9c
standard:	/dev/sdc1
</pre>

<p>
For LABEL mounting:
</p>
<pre>
MOUNT_BU_DISK="mount -L backup-disk-1 $BACKUP_MOUNT_POINT"
</pre>
<p>
For UUID mounting
</p>
<pre>
MOUNT_BU_DISK="mount -U b833d2c1-b824-4d93-a8c9-74e84226rc9c $BACKUP_MOUNT_POINT"
</pre>
<p>
For standard mounting:
</p>
<pre>
MOUNT_BU_DISK="mount /dev/sdc1 $BACKUP_MOUNT_POINT"
</pre>
<p>
For network disk mounting
</p>
<pre>
MOUNT_BU_DISK="mount backupmachine:/dev/sdc1 $BACKUP_MOUNT_POINT"
</pre>
<p>
Unmounting command, should not need to be changed:
</p>
<p>
UNMOUNT_BU_DISK="umount $BACKUP_MOUNT_POINT"
</p>

<h5>
Complex Example
</h5>

<p>
This will mount/umount 2 drives, source and destination, and echoes success messages after each operation.
</p>
<pre>
MOUNT_BU_DISK_10='mount -L audio-bu-1 $BACKUP_MOUNT_POINT &amp;&amp; \
echo "Mounted backup directory $BACKUP_MOUNT_POINT..." &amp;&amp; \
mount musicbox:/home/username/mm $DATA_10_PATH &amp;&amp; \
echo "mounted source directory $DATA_10_PATH..."'
UNMOUNT_BU_DISK_10='umount $BACKUP_MOUNT_POINT &amp;&amp; \
echo "Unmounted $BACKUP_MOUNT_POINT..." &amp;&amp; \
umount $DATA_10_PATH &amp;&amp; \
echo "Unmounted $DATA_10_PATH"'
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-backup-jobs">Backup Job Preset Section</h4>

<pre>
########################################################################
#### JOB PRESETS #######################################################
########################################################################
</pre>
<p>
Set with whatever arguments you want to start script with, script will restart with those options
automatically, then run whatever job you set.
</p>
<p>
Jobs consist of &lt;job name> plus ':' plus &lt;sets of rbxi options>
</p>
<p>
This would use mount/umount 3, and skip home/root backup:
</p>
<pre>
BACKUP_JOB_1='system-b-bu: -M 3 -S rh '
</pre>
<p>
This would use mount/umount 2, skip home/root backup and Add the normally turned off DATA_8:
</p>
<pre>
BACKUP_JOB_2='system-c-bu: -M 2 -S rh -A 8'
</pre>
<p>
This is triggered by the -J <1-10> option.
</p>
<pre>
syntax: BACKUP_JOB_2='job-display-name: &lt;job options>'
</pre>
<pre>
BACKUP_JOB_1=':'
BACKUP_JOB_2=':'
BACKUP_JOB_3=':'
BACKUP_JOB_4=':'
BACKUP_JOB_5=':'
BACKUP_JOB_6=':'
BACKUP_JOB_7=':'
BACKUP_JOB_8=':'
BACKUP_JOB_9=':'
BACKUP_JOB_10=':'
</pre>

<h5>Backup Job Examples</h5>

<pre>
BACKUP_JOB_9=' -C 9 -B 10 -M 9 '
</pre>
<p>
This sets Clone job 9, using main backup destination directory 10, using Mount / Umount
set 9
</p>
<pre>
BACKUP_JOB_10=' -c -B 2 -D 2 -M 2 '
</pre>
<p>
This sets standard delete obsolete, autorun backup, using main backup destination directory 2,
with backup destination sub directory 2, using Mount / Umount set 2.
</p>

<p class="small">
<a href="#top">top</a>
</p>
rbxi-values-user-actions
<h4 id="rbxi-values-user-functions">User Defined Pre/Post Mount/Umount Functions Section</h4>

<pre>
########################################################################
#### ADVANCED USER SET FUNCTIONS/ACTIONS ###############################
########################################################################

# The following allow for user customization of rbxi actions using a simple
# api that will run either pre-defined functions or actions when desired.

####--------------------------------------------------------------------
#### PRE/POST MOUNT/UMOUNT FUNCTIONS -----------------------------------
####--------------------------------------------------------------------
</pre>

<p>
Since nobody can anticipate everything you might need to get done, rbxi also includes the option to set and run functions you create and define in this section, and triggered by the -P option unless you set these here in the default variables, PRE_MOUNT_FUNCTION, POST_MOUNT_FUNCTION, POST_UMOUNT_FUNCTION, which will make them run always unless overridden by a specific -P value.
</p>

<pre>
# launches function: pre_mount_tasks()
PRE_MOUNT_FUNCTION=''
PRE_MOUNT_FUNCTION_1=''
PRE_MOUNT_FUNCTION_2=''
PRE_MOUNT_FUNCTION_3=''
PRE_MOUNT_FUNCTION_4=''
PRE_MOUNT_FUNCTION_5=''
PRE_MOUNT_FUNCTION_6=''
PRE_MOUNT_FUNCTION_7=''
PRE_MOUNT_FUNCTION_8=''
PRE_MOUNT_FUNCTION_9=''
PRE_MOUNT_FUNCTION_10=''

# launches function post_mount_tasks()
POST_MOUNT_FUNCTION=''
POST_MOUNT_FUNCTION_1=''
POST_MOUNT_FUNCTION_2=''
POST_MOUNT_FUNCTION_3=''
POST_MOUNT_FUNCTION_4=''
POST_MOUNT_FUNCTION_5=''
POST_MOUNT_FUNCTION_6=''
POST_MOUNT_FUNCTION_7=''
POST_MOUNT_FUNCTION_8=''
POST_MOUNT_FUNCTION_9=''
POST_MOUNT_FUNCTION_10=''

# launches function post_umount_tasks()
POST_UMOUNT_FUNCTION=''
POST_UMOUNT_FUNCTION_1=''
POST_UMOUNT_FUNCTION_2=''
POST_UMOUNT_FUNCTION_3=''
POST_UMOUNT_FUNCTION_4=''
POST_UMOUNT_FUNCTION_5=''
POST_UMOUNT_FUNCTION_6=''
POST_UMOUNT_FUNCTION_7=''
POST_UMOUNT_FUNCTION_8=''
POST_UMOUNT_FUNCTION_9=''
POST_UMOUNT_FUNCTION_10=''
</pre>

<p>
Note a few things: If the first, non numbered variable contains the function, rbxi will always execute that every time it runs, unless overridden by -P 3::2 for example would override or run PRE_MOUNT_FUNCTION_3 and POST_UMOUNT_FUNCTION_2.
</p>
<p>
The argument for -P is constructed like this: [1-10]:[1-10]:[1-10] where 1-10 is optional, ie, you can skip any or all, or run them all, like for example: -P 2:: or -P 2:2:2
</p>
<p>
Note that each function must return 0 for success, and > 0 for failure. rbxi error handling requires this to properly exit and halt on failure. If no error handling is required, then simply return 0 at the end of the function. Functions must be written in Bash. The functions must be named as follows:
</p>
<ul>
<li>For all PRE_MOUNT_FUNCTION, function must be defined as: pre_mount_tasks()</li>
<li>For all POST_MOUNT_FUNCTION, function must be defined as: post_mount_tasks()</li>
<li>For all POST_UMOUNT_FUNCTION, function must be defined as: post_umount_tasks()</li>
</ul>
<p>
Sample:
</p>
<pre>
PRE_MOUNT_FUNCTION_1='pre_mount_tasks(){
	mount -L some-external-drive /data/drive/mount/point || return 1
	return 0
}'
</pre>
<p>
Note two things here: first, the main feature has a return value of > 0 on failure, and if nothing fails, the function returns 0, success. If you want rbxi to do error handling on your functions, they must return > 0 error codes to rbxi, but less than 255 (that's a bash limitation), which will then report the error number using the rbxi error handler. You can have as many tests and error returns as you want in this function, this is just a very simple sample case, for instance, this would be with echoes so you know it's running (highly recommended), you can even use rbxi colors if you want, but I'll leave that up to you to figure out:
</p>
<pre>
PRE_MOUNT_FUNCTION_1='pre_mount_tasks(){
	echo "Mounting some-drive now..."
	mount -L some-drive /data/drive/mount/point || return 1
	echo "Testing test-file exists in mount point: /data/drive/mount/point/..."
	[ -f /data/drive/mount/point/test-file ] || return 2
	echo "Mounting another-drive now..."
	mount -L another-drive /data/drive/mount/point2 || return 3
	echo "Testing test-file exists in mount point: /data/drive/mount/point2/..."
	[ -f /data/drive/mount/point2/test-file ] || return 4
	return 0
}'
</pre>
<p>
Note that the interior echoes use "" whereas the main variable function declaration is used single quotes. Make sure to do that too if you need to use quotes inside the function, or escape any single quote like this: echo "it\'s going to work!"
</p>
<p>
And here you'd just run this command: rbxi -P 1::<br>
in order to trigger this extra function before the first mount runs.
</p>
<p>
Things to remember: these pre/post mount and post umount functions do not depend on anything being mounted, that's just where they will be run physically in the script, ie, before the main mount backup drive function, after the mount main backup drive function, and after the umount backup drive function. If you are skipping mounting the backup drive, with -m, then they will still run.
</p>
<p>
Important! If you use variables in your functions, make sure to either make them local, 
like: local variablename='', or by starting the variables with a prefix: like: ppmm_
that is unique. Otherwise you might accidently overwrite a script variable.
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-user-actions">User Defined Start/Finish/Error Actions (emails)</h4>

<pre>
####--------------------------------------------------------------------
#### EMAILER ACTIONS ---------------------------------------------------
####--------------------------------------------------------------------
</pre>

<p>
These work much the same as above, only they do NOT use a function, just a scripted action, which will for most people be emailing the sys admin, but you can put any actions you want in here as well that you want done that rbxi doesn't do already. Errors from the action cannot be handled unless you make your action scripting itself process it. 
</p>
<p>
You can get rbxi error handling by using the following in your action code, triggered by whatever error condition you want. Error 31 is a generic User Action error code for this feature. Sample:
</p>
<pre>
some email sending procedure || error_handler 31 "your error data"
</pre>
<p>
Note that you need to use quotes for your actual error message "your error data", for example:
</p>
<pre>
error_handler 31 "Script Emailer (method 2) Error on step: finish"
</pre>
</p>

</p>
<p>
Actions must be written in Bash, or any other language you can call directly on the system that is running the backup.
</p>
<p>
These actions will be triggered in a function that will have access to the following data, called with "$data" (" quotes are NOT optional). $data is time stamped always for start/finish/error.
</p>
<ul>
<li>EMAIL_START_ACTION: $data is the startup options rbxi is running with, and the start time</li>
<li>EMAIL_FINISH_ACTION: $data is the startup options, plus the finish time.</li>
<li>EMAIL_ERROR_ACTION: $data is the error message from the error handler, including error numbers and error time.
</li>
</ul>

<p>
Actions can be any Bash command your system supports, of any complexity, including but not limited to sending emails using system emailers like exim4 or mail or whatever you want. The Action will execute when the script starts, when it finishes, and if error occurs, if you select these options, depending on how you use these options.
</p>

<pre>
# Alerts to start of backup operation
EMAIL_START_ACTION=''
EMAIL_START_ACTION_1=''
EMAIL_START_ACTION_2=''
EMAIL_START_ACTION_3=''
EMAIL_START_ACTION_4=''
EMAIL_START_ACTION_5=''
EMAIL_START_ACTION_6=''
EMAIL_START_ACTION_7=''
EMAIL_START_ACTION_8=''
EMAIL_START_ACTION_9=''
EMAIL_START_ACTION_10=''

# Alerts to finish of backup operation
EMAIL_FINISH_ACTION=''
EMAIL_FINISH_ACTION_1=''
EMAIL_FINISH_ACTION_2=''
EMAIL_FINISH_ACTION_3=''
EMAIL_FINISH_ACTION_4=''
EMAIL_FINISH_ACTION_5=''
EMAIL_FINISH_ACTION_6=''
EMAIL_FINISH_ACTION_7=''
EMAIL_FINISH_ACTION_8=''
EMAIL_FINISH_ACTION_9=''
EMAIL_FINISH_ACTION_10=''

# Alerts to backup error, should include error data.
EMAIL_ERROR_ACTION=''
EMAIL_ERROR_ACTION_1=''
EMAIL_ERROR_ACTION_2=''
EMAIL_ERROR_ACTION_3=''
EMAIL_ERROR_ACTION_4=''
EMAIL_ERROR_ACTION_5=''
EMAIL_ERROR_ACTION_6=''
EMAIL_ERROR_ACTION_7=''
EMAIL_ERROR_ACTION_8=''
EMAIL_ERROR_ACTION_9=''
EMAIL_ERROR_ACTION_10=''
</pre>

<p>
Note a few things: If the first, non numbered variable contains the action, rbxi will always execute that every time it runs, unless overridden by -E 3::2 for example would override or run EMAIL_START_ACTION_3 and EMAIL_FINISH_ACTION_2.
</p>
<p>
The argument for -E is constructed like this: [1-10]:[1-10]:[1-10] where 1-10 is optional, ie, you can skip any or all, or run them all, like for example: -P 2:: or -P 2:2:2
</p>
<p>
Rbxi does not do error handling on your commands, so make sure to debug them completely before you rely on this for production use.
</p>

<p>
Sample (I'm not sure you can use &lt;&lt;&lt; "$data" with nail, this is just a sample, always test your code before putting it live):
</p>
<pre>
EMAIL_ERROR_ACTION_1='nail -r "myaddress@something.com" -s "Backup Error on Raven" -S smtp=some.smtp.server info@company.com &lt;&lt;&lt; "$data"'
</pre>

<p>
If you prefer, you can also just write a separate function, then include it, say you create a file: rbxi-extra-functions<br>
put it in rbxi-data, which let's say is in /usr/local/bin, then, above: # Alerts to start of backup operation<br>
you would add this line: source /usr/local/bin/rbxi-data/rbxi-extra-functions<br>
then you could simply call your function like so (let's say your function is called: email_processing. Remember that the $data variable must always be in double quotes: "$data".
</p>
<pre>
EMAIL_ERROR_ACTION_1='email_processing startup "$data"'
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-clean-delete">Clean Delete Backup Skip Section</h4>

<pre>
########################################################################
#### CLEAN / DELETE / BACKUP / SKIP ####################################
########################################################################
</pre>
<p>
These are for options, used in case of cron or option run backups/deletes
if you want to hard set any option just set the variable to true.
trigger rdiff/rsync cleeanup, either older than x, or remove deleted files
</p>
<pre>
B_CLEAN_OLDER='false' # -c :clean old backup files, then do backup
B_DELETE_BACKUP='false' # -d :delete old backup, then do backup
B_DO_BACKUP='false' # -b :automatic backup
</pre>
<p>
Skip home/root/data can be overridden by -A &lt;r|h|number> when you are creating
a separate job (-J &lt;number>).
</p>

<pre>
B_SKIP_DATA_FULL='false' # -C [..] or -S d - skips all data partition backups
B_SKIP_DATA_1='false' # -S 1
B_SKIP_DATA_2='false' # -S 2
B_SKIP_DATA_3='false' # -S 3
B_SKIP_DATA_4='false' # -S 4
B_SKIP_DATA_5='false' # -S 5
B_SKIP_DATA_6='false' # -S 6
B_SKIP_DATA_7='false' # -S 7
B_SKIP_DATA_8='false' # -S 8
B_SKIP_DATA_9='false' # -S 9
B_SKIP_DATA_10='false' # -S 10
B_SKIP_HOME='false' # -S h
B_SKIP_ROOT='false' # -S r
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-misc-options">Miscellaneous Script Options Section</h4>

<pre>
########################################################################
#### MISCELLANEOUS SCRIPT OPTIONS ######################################
########################################################################
</pre>

<h5>Miscellaneous Script Booleans (true/false)</h5>

<p>
<pre>
B_SKIP_MOUNT='false' # -m :do not mount backup drive, or umount it
B_SPINNING_WHEEL='false' # -s :use spinning wheel option
B_TESTING_1='false' # -! 1 :testing flag 1
B_TESTING_2='false' # -! 2 :testing flag 2
</pre>
<p>
If you want rbxi to notify you of newer versions when it runs, set to true.
Default is false, no checking for latest versions.
</p>
<p>
<pre>
B_UPDATE_NOTIFIER='false'
</pre>

<h5>Script Color Schemes</h5>

<pre>
0 - no colors
1 - default, for dark on light or light on dark, red warning/error, simple highlights
2 - fancy dark on light, red warning/error, more colors for questions, highlights
3 - basic light on dark, red warning, yellow error, simple colored highlights
4 - fancy light on dark, red warning, yellow error, fancy colored highlights
5 - smxi style, for light on dark, green text, otherwise same as 3
Try each one and see which works best for your terminal colors using -j <0-5>, then set it here.
COLOR_SCHEME='1' # -j [0-5]
</pre>

<h5>Set console browser</h5>
<p>
Uncomment then set only if you want to override the default console browser rbxi selects
to show readme-rbxi.htm with -R option.
</p>
<pre>
# CONSOLE_BROWSER=''
</pre>

<h5>Logging options</h5>
<p>
Default is logging on. To turn off, change to 'false'. If you want to override a false, use -l option when starting rbxi and it will use logging for just that session.
</p>
<pre>
B_LOGGING='true'
</pre>
<p>
You can manually override the default logfile directory location here if you want (must end with /). Uncomment if you want to change rbxi default location to somewhere else in your system.
</p>
<pre>
# LOGFILE_DIR='/var/log/'
</pre>
<p>
Log file max size, in kB. Must be an integer, for example: LOGFILE_SIZE=500<br>
Overrides script default size of 100kB. Uncomment to use override. Rbxi will automatically rotate the file one time, to rbxi.1.log in the logfile directory once it hits the size in kB given.
</p>
<pre>
# LOGFILE_SIZE=100
</pre>

<h5>Sleep Times</h5>

<p>
These sleep times are all in seconds.
</p>
<pre>
SLEEP_TIME_SPINNER='0.5'
</pre>
<p>
If you started the script with the -s option, a small spinning wheel will
run as each part of the operation is carried out. This lets you know
that something is happening, that is.
</p>
<p>
I found that setting this to a lower number tended to boost the cpu useage, but
you can play with it to see for yourself. Anything less then 0.1 would be
pointless. I find that 0.5 is fine, and doesn't consume much cpu. The lower the
number, the faster the wheel spins.
</p>
<pre>
SLEEP_TIME_BACKUP='3'
</pre>
<p>
Time between backup operations, make integer, number of seconds
</p>
<pre>
SLEEP_TIME_UMOUNT='5'
</pre>
<p>
Time forced exit allows for disk write syncs before umount occurs. If umount
fails with busy error on forced or premature exit, set this integer to be higher.
</p>

<p class="small">
<a href="#top">top</a>
</p>

<h4 id="rbxi-values-final-step">Final Configuration Step</h4>

<pre>
########################################################################
#### FINAL STEP - DO NOT SKIP! #########################################
########################################################################
</pre>
<p>
And last but not least, set this to 'true' once you are done updating all the variables here.
Failure to do this will make rbxi exit without running, since you can't run it without having
completed the user variables in the file: rbxi-data/rbxi-values
</p>
<pre>
B_VARIABLES_SET='false'
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h2 id="rbxi-static-variables">Static Variables :: Should Not Require Changes</h2>

<p>
These variables should not be changed unless you have some particularly good
reason to do that, such as needing to reset the script or lsof path.
</p>
<p>
Do not change any of these, these are simply initializing variables.
</p>

<pre>
#### INITIALIZE VARIABLES TO BE SET ELSEWHERE
B_CLONE_HOME='false'
B_CLONE_ROOT='false'
B_CLONE_DATA_1='false'
B_CLONE_DATA_2='false'
B_CLONE_DATA_3='false'
B_CLONE_DATA_4='false'
B_CLONE_DATA_5='false'
B_CLONE_DATA_6='false'
B_CLONE_DATA_7='false'
B_CLONE_DATA_8='false'
B_CLONE_DATA_9='false'
B_CLONE_DATA_10='false'
B_DELETE_STATUS='false'
B_IS_CLONE='false'
HOME_BACKUP=''
ROOT_BACKUP=''
DATA_1_BACKUP=''
DATA_2_BACKUP=''
DATA_3_BACKUP=''
DATA_4_BACKUP=''
DATA_5_BACKUP=''
DATA_6_BACKUP=''
DATA_7_BACKUP=''
DATA_8_BACKUP=''
DATA_9_BACKUP=''
DATA_10_BACKUP=''
HOME_BU_COMMAND=''
ROOT_BU_COMMAND=''
DATA_1_BU_COMMAND=''
DATA_2_BU_COMMAND=''
DATA_3_BU_COMMAND=''
DATA_4_BU_COMMAND=''
DATA_5_BU_COMMAND=''
DATA_6_BU_COMMAND=''
DATA_7_BU_COMMAND=''
DATA_8_BU_COMMAND=''
DATA_9_BU_COMMAND=''
DATA_10_BU_COMMAND=''
ENDING_1='...'
ENDING_2='...'
START_TIME=$( date +%s )
BACKUP_CLEAR=''
BACKUP_DURATION=''
BACKUP_JOB_NU='none'
DELETION_TEXT=''
GET_PID=''
RSYNC_DELETE=''
</pre>

<p class="small">
<a href="#top">top</a>
</p>

<h2 id="rbxi-functions">Rbxi Functions</h2>

<p>
<strong>PLEASE ONLY CHANGE IF YOU CAN DO SOME BASH SCRIPTING</strong>
</p>

<ul>
	<li>
		<pre>run_backup_components</pre>

		<p>
		The only thing I could see any user wanting to change here would be adding
		more primary backups. That's fairly trivial, just create the user variables for data_3, data_4
		etc, then add more if that exists items like you see there.
		</p>
		<p>
		There is no need to remove anything here by default, since if the primary backup directory
		name is blank, that backup won't run.
		</p>
	</li>
</ul>

<p class="small">
<a href="#top">top</a>
</p>

<h2>OK, THAT'S IT, HAVE FUN!</h2>

</div>
</body>
</html>
